Creating a Mobile-Friendly Donations Form with the Convio Donations API


The steps below outline how you can create a donation form using Convio's Donation API that is optimized for mobile devices like the iPhone. Creating this form will require a moderate level of technical knowledge and comfort with editing raw HTML. For those organizations needing assistance, Convio offers a low-cost Services engagement to implement a mobile-friendly form. Contact your Account Manager if you're interested in that!

What you'll need before you get started ...

Before you start coding, you'll want to have the following prepared:

One other important requirement: The Site Option CONVIO_API_KEY must have some value. The API won't work if it doesn't!

Step 1) Create the "ghost" donation form to be used

The first step when implementing the Donation API is to create a donation form in the Donation Management area of the product as you would normally. The form should include only the basic billing fields:

Including additional fields is technically possible of course, but for the purposes of this example is not included.

Be sure that the appropriate autoresponders are configured for the form.

Step 2) Create reusable PageBuilder page reus_isMobile

With the WYSIWYG disabled, copy and paste the contents of reus_isMobile.txt into a reusable page named reus_isMobile. No need to change this page at all.

Step 3) Update "Additional HTML Tags for HEAD Element" area of  the page wrapper

Add the following to the head of your site's page wrapper. Update the df_id,  "1180", with the id of the donation form to use if a user views the page on a non-mobile device. This can be one of your existing general donation forms.

Note the "Normal head of wrapper goes here" HTML comment. This  should, of course, be replaced with the actual head of the wrapper. The idea here is to minimize the amount of overhead on mobile devices, so all of the normal stylesheets, JavaScript, etc. are conditionalized out.

[[S51:reus_isMobile]]
[[?[[S80:isMobile]]::1::
     [[?x[[?[[S80:UserAgentLowerCase]]::iphone::T::]]x[[?[[S80:UserAgentLowerCase]]:: pre/::T::]]x::xTx::
          <meta name="viewport" content="width=320; initial-scale=1.0; maximum-scale=1.0; user-scalable=0;" />
     ::]]
     <style type="text/css">
     body{
          padding: 0.75em;
     }
     </style>
::
     [[?xdonatenowx::x[[S334:pagename]]x::
          <script type="text/javascript">
               window.location='https://[[S29:SECURE_DOMAIN]][[S29:SECURE_PATH]]Donation2?idb=[[S76:idb]]&df_id=1180';
          </script>
          <meta http-equiv="refresh" content="0;url=https://[[S29:SECURE_DOMAIN]][[S29:SECURE_PATH]]Donation2?idb=[[S76:idb]]&df_id=1180">
     ::]]
     <!--Normal head of wrapper goes here-->
]]

Step 4) Update "HTML Body" of the page wrapper

Add the following to the HTML body of the wrapper. Change out the  reference to images/logo.jpg to the banner image you want to be displayed above your form, or remove this line if you don't wish to include an image. Depending how wide the image is,  you may want to add an inline style="width: 100%;" to prevent the image  from extending outside the phone's viewport.

Note the "Normal body of wrapper goes here" HTML comment. This should  be replaced with the actual body of the wrapper. What this code does is minimize the HTML around the content area to nothing but the single div "mobile-container".

[[?[[S80:isMobile]]::1::
     <div id="mobile-container">
          <p><img alt="[[S0:SITE_NAME]]" src="../images/logo.jpg" /></p>
          <div style="margin-top: 0.75em;">
               [[?[[S334:pagename]]::donatenow::[[E51:[[S334:pagename]]]]::[[S63:3]]]]
          </div>
     </div>
::
     <!--Normal body of wrapper goes here-->
]]

Step 5) Create secure PageBuilder page donatenow

Copy and paste the contents of donatenow.txt  into a PageBuilder page named donatenow (you can use a different name if you like). Update the session variables (the U-Tags)  atop the source code as instructed for the form_id and the donation level ids,  amounts, and if applicable names. Modify the copy at the top and bottom  of the form as needed.

Nothing else on the form should need to be changed, as it is dynamic!


Step 6) Create secure PageBuilder page donatenow_thanks

Copy and paste the contents of donatenow_thanks.txt  into a PageBuilder page named donatenow_thanks (or, if you used a different pagename in Step 5, append _thanks to that). Modify the copy as  needed.

You're done!

You can now link to the form as http://www.site.org/donatenow  (where site.org is your Convio non-secure domain). On a mobile device, this will  resolve to the new form you created, and on anything else it will  resolve to the donation form referenced in Step 3.

Note: While http://www.site.org/donatenow is a great short URL to use on, say, posts on Twitter, when sending e-mails to  this form through Convio, you should use the full URL  https://secure2.convio.net/shortname/site/SPageServer?pagename=donatenow&autologin=true  (changing out the secure domain and shortname as needed), so that users  will be automatically logged in.


Optional Step 7) Redirect normal donation form to mobile version

Once you've completed testing the mobile form, you can redirect all of your site's donation form(s) to the new  mobile form on mobile devices. To do this, you'll need to update the  code you put in the head of the wrapper in Step 4, like so (again,  updating the df_id, 1180, to your non-mobile form's id):

[[S51:reus_isMobile]]
[[?[[S80:isMobile]]::1::
     [[?x1180x::x[[S334:df_id]]x::
          <script type="text/javascript">
               window.location='https://[[S29:SECURE_DOMAIN]][[S29:SECURE_PATH]]SPageServer?pagename=donatenow';
          </script>
          <meta http-equiv="refresh" content="0;url=https://[[S29:SECURE_DOMAIN]][[S29:SECURE_PATH]]SPageServer?pagename=donatenow">
     ::]]
     [[?x[[?[[S80:UserAgentLowerCase]]::iphone::T::]]x[[?[[S80:UserAgentLowerCase]]:: pre/::T::]]x::xTx::
          <meta name="viewport" content="width=320; initial-scale=1.0; maximum-scale=1.0; user-scalable=0;" />
     ::]]
     <style type="text/css">
     body{
          padding: 0.75em;
     }
     </style>
::
     [[?xdonatenowx::x[[S334:pagename]]x::
          <script type="text/javascript">
               window.location='https://[[S29:SECURE_DOMAIN]][[S29:SECURE_PATH]]Donation2?idb=[[S76:idb]]&df_id=1180';
          </script>
          <meta http-equiv="refresh" content="0;url=https://[[S29:SECURE_DOMAIN]][[S29:SECURE_PATH]]Donation2?idb=[[S76:idb]]&df_id=1180">
     ::]]
     <!--Normal head of wrapper goes here-->
]]

Again, this should only be done after you've  verified the new mobile form you created is working correctly. Once you  make this change, mobile users who access the normal donation form will  be redirected to your new form.

While this is an optional step, it is a best practice that is  highly recommended.